home *** CD-ROM | disk | FTP | other *** search
/ QRZ! Ham Radio 5 / QRZ Ham Radio Callsign Database - Volume 5.iso / unix / src / qrztech.txt < prev    next >
Text File  |  1994-11-27  |  9KB  |  215 lines
  1.  
  2. June 1994 - no changes from October 1993
  3.  
  4.  
  5.  
  6. The QRZ! Ham Radio CDROM 
  7. Callsign Database Technical Specification          October 1993 
  8. by Fred Lloyd, AA7BQ
  9.  
  10.  
  11. Note: the following information is provided for those who wish to
  12. access the callsign database information without the use of the QRZ!
  13. software.  Users of the QRZ! Ham Radio CDROM who wish to write their
  14. own callsign database search and retrieval software are encouraged to
  15. do so.  We welcome user contributed shareware programs for future
  16. versions of the QRZ! Ham Radio CDROM.
  17.  
  18.  
  19.  
  20. BACKGROUND
  21.  
  22. The support software for the QRZ! callsign database is supplied in
  23. three versions, two for the PC and one for the UNIX operating system.
  24. None of the versions are supported by Walnut Creek CDROM or by the
  25. author.  If you are not satisfied with the QRZ! software you may return
  26. the CDROM to Walnut Creek for a full refund.
  27.  
  28.  
  29.  
  30. PC VERSIONS
  31.  
  32. For the PC, there are two versions of the QRZ! software, one for DOS
  33. and one for Windows 3.1.  Both versions use the same copy of the
  34. database and the same general search and retrieval methods.  The
  35. following discussion applies to both versions of the search software.
  36. Any differences will be noted accordingly.
  37.  
  38. The QRZ callsign database indexing and retrieval method was designed
  39. and optimized for CDROM use.  The primary goal was to provide fast
  40. access for searches in light of the fact that typical CDROM seek times
  41. are somewhat slow compared to hard disk.  The algorithm described below
  42. implements a methodology which requires only one  CDROM  disc seek per
  43. lookup.
  44.  
  45. The QRZ callsign database is organized as a set of four sorted copies
  46. of the complete list of amateur radio records.  One copy is sorted by
  47. callsign, one by last name, one by city-state and one by zip code.
  48.  
  49. There is a corresponding index file for each of the sorted databases.
  50. The index file contains selected keys from the corresponding database
  51. sampled at regular intervals.  The key sampling interval is stored in
  52. the index header as bytesperkey, as shown in the structure definition
  53. below.
  54.  
  55.  
  56. New Index Header Format
  57.  
  58. The layout of the index header was changed from the last version
  59. of the QRZ! Ham Radio CDROM in order to accommodate a machine
  60. independent format.  All index header fields are now stored as null
  61. terminated ASCII strings.  Both the old and the new index header
  62. formats are shown below:
  63.  
  64.  
  65. /*
  66. **      Old Index Header Block Definition
  67. **
  68. **      This block is located at the start of each index
  69. */
  70. typedef struct {
  71.   char  dataname[13];   /* Name of the data file            */
  72.   ulong bytesperkey;    /* Data Bytes per Index Item        */
  73.   uint  numkeys;        /* Number of items in this index    */
  74.   uint  keylen;         /* Length of each key item in bytes */
  75. } old_index_header ;
  76.  
  77. The old index header format is obsolete and will not be used in
  78. the current or future versions of the database.
  79.  
  80.  
  81. /*
  82. **     New Index Header Block Definition
  83. **
  84. **     This block is located at the start of each index
  85. */
  86. typedef struct {
  87.   char  dataname[16];    /* Name of the data file            */
  88.   char  bytesperkey[8];  /* Data Bytes per Index Item        */
  89.   char  numkeys[8];      /* Number of items in this index    */
  90.   char  keylen[8];       /* Length of each key item in bytes */
  91.   char  version[8];      /* Database Version ID              */
  92. } index_header;
  93.  
  94.  
  95. The old index type may be quickly distinguished by looking for a
  96. '0' at offsets 16 and 17.  For example, suppose you have read the
  97. header structure into a character array called 'hdr'.  The following
  98. will identify the old header style on a machine with 16 bit integers
  99. (i.e. a PC):
  100.  
  101.     if ((int)hdr[16] == 0)
  102.         /* header is old style */
  103.     
  104.     else
  105.         /* header is new style */
  106.  
  107.  
  108. This works beause 'bytesperkey' in the new style is never zero and
  109. the value is always left justified in the structure member.
  110.  
  111.  
  112. Index Usage
  113.  
  114. The name index is set to a maximum of 16 characters with longer names
  115. being truncated.   Names are stored in last-first format with a space
  116. between the names.  The city/state index uses 12 characters per entry,
  117. the callsign index 6 characters and the zip code index 5 characters.
  118.  
  119. The data which follows the header is simply a long list of single field
  120. records. The records are tightly packed on 'bytesperkey' boundaries
  121. without separators.  There is no guarantee of a null terminator on any
  122. index record entry.
  123.  
  124. When the program qrz.exe is run it first searches for a drive
  125. containing the base directory \CALLBK .  Next, it loads all four index
  126. files (callbkc.idx, callbkn.idx, callbks.idx and callbkz.idx) into
  127. tables in memory.  These tables were kept small so as not to place an
  128. undue RAM requirement on the user's system.
  129.  
  130. Next, when a user specifies a field and key to search, the program
  131. searches the relevant index table and returns the closest match lower
  132. (or equal to) the supplied key.  The table position of this key is then
  133. taken and multiplied by the 'bytesperkey' value to arrive at a database
  134. file offset.  This offset is then used to perform the first and only
  135. seek into the database.  Once on position within the file, a sequential
  136. search is performed to return the match.  The search terminates at the
  137. next index key value if the field is not found.
  138.  
  139. The database files all have the same format.  The records each consist
  140. of comma separated fields which end with a single newline '\n'  (ASCII
  141. 0xa) character.  Blank fields are simply stored as a comma.  Every
  142. record has the same number of commas in it.  Actual comma's in the data
  143. field are stored as a semi-colon ';' which should be replaced by a
  144. comma in the user's output formatting routine.
  145.  
  146.  
  147. /*
  148. **    Standard Record Format
  149. */
  150. char callsign[6];         /* Call Sign Decoded      */
  151. char lastname[32];        /* Last Name              */
  152. char namesuffix[2];       /* Name Suffix            */
  153. char frstname[32];        /* First Name             */
  154. char middleinit[1];       /* Middle Initial         */
  155. char streetaddr[32];      /* Street Address         */
  156. char city[32];            /* City                   */
  157. char state[2];            /* State Code             */
  158. char datelicensed[5];     /* Date Licensed mm/dd/yy */
  159. char dateborn[5];         /* Date Born              */
  160. char license_class[1];    /* License Class          */
  161. char zipcode[5];          /* Zip Code               */
  162. char prevcall[6];         /* Previous Call          */
  163. char prevclass[1];        /* Previous Class         */
  164.  
  165.  
  166. The callsign fields are arranged in a strict "ccdccc" columnar format
  167. where 'c' represents a letter and 'd' a digit. Callsigns which do not
  168. conform to the "ccdccc" format are space filled in the relevant
  169. positions.  This field is rearranged to the proper layout by the user
  170. program's output formatting routines.
  171.  
  172. All dates are stored in 5 character Julian format, e.g. 93003 equals
  173. January 3, 1993.  Dates before 1900 or after year 2000 must be
  174. determined by their context usage (good luck).
  175.  
  176. Some will notice that the database no longer contains station location
  177. information.  This information is no longer supplied nor available from
  178. the FCC since it is no longer a part of their record keeping (See the
  179. May 1993 QST for more info).
  180.  
  181.  
  182. Cross Reference Information
  183.  
  184. Callsigns in the database are now cross-referenced to both the current
  185. and the previous call sign for each entry in which they are available.
  186. A cross reference record takes the form of 'old,new' with no other
  187. information in the record.  A record can be identified as a cross
  188. reference either one of two ways:
  189.  
  190.     First, if the record length is less than 15 characters, then
  191.     it is a cross reference record.
  192.  
  193.     Secondly, if the record contains only one comma "," , then
  194.     it is a cross reference record.
  195.  
  196. It is not necessary to test for both cases, either will do.
  197.  
  198. When a cross reference record is encountered, you must fetch the second
  199. field and restart the search to return the primary reference.
  200.  
  201.  
  202.  
  203. UNIX VERSION
  204.  
  205. Another copy of the database exists on the CD in the /unix directory.
  206. Full UNIX source code is included in this directory as is a readme file
  207. explaining its use.
  208.  
  209.  
  210. Thank you for buying the QRZ! Ham Radio CDROM
  211.  
  212. New programs, and other submissions to future QRZ! Ham Radio CDROM
  213. editions should be sent to Walnut Creek CDROM, preferably by anonymous
  214. ftp to ftp.cdrom.com.
  215.